home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / C Internet Config / IC Resource ƒ / IC Headers ƒ / IC API Descriptions.h < prev    next >
Encoding:
Text File  |  1995-11-17  |  21.4 KB  |  367 lines  |  [TEXT/SPM ]
  2.     Set folders to a pointer to the folders to search.
  3.     Setting count to 0 and folders to nil is OK.
  4.     Searches the specified folders and then optionally the Preferences folder
  5.     in a unspecified manner.
  6. */
  7.  
  8. ICError ICChooseConfig(ICInstance inst);
  9. /*
  10.     Requires IC 1.2.
  11.     It is illegal to call this routine inside a ICBegin/End pair.
  12.     Requests the user to choose a configuration, typically using some
  13.     sort of modal dialog. If the user cancels the dialog the configuration
  14.     state will be unaffected.
  15. */
  16.  
  17. ICError ICChooseNewConfig(ICInstance inst);
  18. /*
  19.     Requires IC 1.2.
  20.     It is illegal to call this routine inside a ICBegin/End pair.
  21.     Requests the user to create a new configuration, typically using some
  22.     sort of modal dialog. If the user cancels the dialog the configuration
  23.     state will be unaffected.
  24. */
  25.  
  26. ICError ICGetConfigName(ICInstance inst,Boolean longname,StringPtr name);
  27. /*
  28.     Requires IC 1.2.
  29.     You must specify a configuration before calling this routine.
  30.     Returns a string that describes the current configuration at a user
  31.     level. Set longname to true if you want a long name, up to 255
  32.     characters, or false if you want a short name, typically about 32
  33.     characters.
  34.     The returned string is for user display only. If you rely on the
  35.     exact format of it, you will conflict with any future IC
  36.     implementation that doesn't use explicit preference files.
  37. */
  38.  
  39. ICError ICGetConfigReference(ICInstance inst,ICConfigRefHandle ref);
  40. /*
  41.     Requires IC 1.2.
  42.     You must specify a configuration before calling this routine.
  43.     Returns a self-contained reference to the instance's current
  44.     configuration.
  45.     ref must be a valid non-nil handle and it will be resized to fit the
  46.     resulting data.
  47. */
  48.  
  49. ICError ICSetConfigReference(ICInstance inst,ICConfigRefHandle ref,long flags);
  50. /*
  51.     Requires IC 1.2.
  52.     It is illegal to call this routine inside a ICBegin/End pair.
  53.     Reconfigures the instance using a configuration reference that was
  54.     got using ICGetConfigReference reference. Set the
  55.     icNoUserInteraction_bit in flags if you require that this routine
  56.     not present a modal dialog. Other flag bits are reserved and should
  57.     be set to zero.
  58.     ref must not be nil.
  59. */
  60.  
  61. ICError ICSpecifyConfigFile(ICInstance inst,FSSpec* config);
  62. /*
  63.     It is illegal to call this routine inside a ICBegin/End pair.
  64.     For use only by the IC application.
  65.     If you call this routine yourself, you will conflict with any
  66.     future IC implementation that doesn't use explicit preference files.
  67. */
  68.  
  69. /* ***** Getting Information ***** */
  70.  
  71. ICError ICGetSeed(ICInstance inst,long* seed);
  72. /*
  73.     You do not have to specify a configuration before calling this routine.
  74.     You do not have to be inside an ICBegin/End pair to call this routine.
  75.     Returns the current seed for the IC prefs database.
  76.     This seed changes each time a non-volatile preference is changed.
  77.     You can poll this to determine if any cached preferences change.
  78. */
  79.  
  80. ICError ICGetPerm(ICInstance inst,ICPerm* perm);
  81. /*
  82.     You do not have to specify a configuration before calling this routine.
  83.     Returns the access permissions currently associated with this instance.
  84.     While applications normally know what permissions they have,
  85.     this routine is designed for use by override components.
  86. */
  87.  
  88. ICError ICDefaultFileName(ICInstance inst,StringPtr name);
  89. /*
  90.     You do not have to specify a configuration before calling this routine.
  91.     You do not have to be inside an ICBegin/End pair to call this routine.
  92.     Returns the default file name for IC preference files.
  93.     Applications should never need to call this routine.
  94.     If you rely on information returned by this routine yourself,
  95.     you may conflict with any future IC implementation that doesn't use
  96.     explicit preference files.
  97.     The component calls this routine to set up the default IC file name.
  98.     This allows this operation to be intercepted by a component that has
  99.     captured us. It currently gets it from the component resource file.
  100.     The glue version is hardwired to "Internet Preferences".
  101. */
  102.  
  103. ICError ICGetComponentInstance(ICInstance inst,Ptr* component_inst);
  104. /*
  105.     Requires IC 1.2.
  106.     You do not have to specify a configuration before calling this routine.
  107.     You do not have to be inside an ICBegin/End pair to call this routine.
  108.     Returns noErr and the connection to the IC component,
  109.     if we're using the component.
  110.     Returns badComponenInstance and nil if we're operating with glue.
  111.     The component_inst parameter is a universal pointer to avoid
  112.     us having to include Component.[ph] (which is not available under
  113.     some development environments) in order to use IC.
  114. */
  115.  
  116. /* ***** Reading and Writing Preferences ***** */
  117.  
  118. ICError ICBegin(ICInstance inst,ICPerm perm);
  119. /*
  120.     You must specify a configuration before calling this routine.
  121.     It is illegal to call this routine inside a ICBegin/End pair.
  122.     Starting reading or writing multiple preferences.
  123.     A call to this must be balanced by a call to ICEnd.
  124.     Do not call WaitNextEvent between these calls.
  125.     The perm specifies whether you intend to read or read/write.
  126.     Only one writer is allowed per instance.
  127.     Note that this may open resource files that are not closed
  128.     until you call ICEnd.
  129. */
  130.  
  131. ICError ICGetPref(ICInstance inst,StringPtr key,ICAttr* attr,Ptr buf,long* size);
  132. /*
  133.     You must specify a configuration before calling this routine.
  134.     If you are getting or setting multiple preferences, you should place
  135.     these calls within an ICBegin/ICEnd pair.
  136.     If you call this routine outside of such a pair, it implicitly
  137.     calls ICBegin(inst, icReadOnlyPerm).
  138.     Reads the preference specified by key from the IC database to the
  139.     buffer pointed to by buf and size.
  140.     key must not be the empty string.
  141.     If buf is nil then no data is returned.
  142.     size must be non-negative.
  143.     attr and size are always set on return. On errors (except icTruncatedErr)
  144.     attr is set to ICattr_no_change and size is set to 0.
  145.     size is the actual size of the data.
  146.     attr is set to the attributes associated with the preference.
  147.     If this routine returns icTruncatedErr then the other returned
  148.     values are valid except that only the first size bytes have been
  149.     return. size is adjusted to reflect the true size of the preference.
  150.     Returns icPrefNotFound if there is no preference for the key.
  151. */
  152.  
  153. ICError ICSetPref(ICInstance inst,StringPtr key,ICAttr attr,Ptr buf,long size);
  154. /*
  155.     You must specify a configuration before calling this routine.
  156.     If you are getting or setting multiple preferences, you should place
  157.     these calls within an ICBegin/ICEnd pair.
  158.     If you call this routine outside of such a pair, it implicitly
  159.     calls ICBegin(inst, icReadWritePerm).
  160.     Sets the preference specified by key from the IC database to the
  161.     value pointed to by buf and size.
  162.     key must not be the empty string.
  163.     size must be non-negative. 
  164.     If buf is nil then the preference value is not set and size is ignored.
  165.     If buf is not nil then the preference value is set to the size
  166.     bytes pointed to by buf.
  167.     If attr is ICattr_no_change then the preference attributes are not set.
  168.     Otherwise the preference attributes are set to attr.
  169.     Returns icPermErr if the previous ICBegin was passed icReadOnlyPerm.
  170.     Returns icPermErr if current attr is locked, new attr is locked and buf <> nil.
  171. */
  172.  
  173. ICError ICFindPrefHandle(ICInstance inst,StringPtr key,ICAttr* attr,Handle prefh);
  174. /*
  175.     Requires IC 1.2.
  176.     You must specify a configuration before calling this routine.
  177.     If you are getting or setting multiple preferences, you should place
  178.     these calls within an ICBegin/ICEnd pair.
  179.     If you call this routine outside of such a pair, it implicitly
  180.     calls ICBegin(inst, icReadWritePerm).
  181.     This routine effectively replaces ICGetPrefHandle.
  182.     Reads the preference specified by key from the IC database into
  183.     a handle, prefh.
  184.     key must not be the empty string.
  185.     attr is set to the attributes associated with the preference.
  186.     You must set prefh to a non-nil handle before calling this routine.
  187.     If the preference does not exist, icPrefNotFoundErr is returned.
  188. */
  189.  
  190. ICError ICGetPrefHandle(ICInstance inst,StringPtr key,ICAttr* attr,Handle* prefh);
  191. /*
  192.     Requires IC 1.1.
  193.     You must specify a configuration before calling this routine.
  194.     If you are getting or setting multiple preferences, you should place
  195.     these calls within an ICBegin/ICEnd pair.
  196.     If you call this routine outside ofty string then URLs of that form are not allowed.
  197.     data points to the start of the text. It must not be nil.
  198.     len indicates the length of the text. It must be non-negative.
  199.     selStart and selEnd should be passed in as the current selection of
  200.     the text. This selection is given in the same manner as TextEdit,
  201.     ie if selStart = selEnd then there is no selection only an insertion
  202.     point. Also selStart ≤ selEnd and 0 ≤ selStart ≤ len and 0 ≤ selEnd ≤ len.
  203.     selStart and selEnd are returned as the bounds of the URL. If the
  204.     routine returns an error then these new boundaries may be
  205.     invalid but they will be close.
  206.     The incoming url handle must not be nil.  The resulting URL is normalised
  207.     and copied into the url handle, which is resized to fit.
  208. */
  209.  
  210. ICError ICLaunchURL(ICInstance inst,StringPtr hint,Ptr data,long len,long* selStart,long* selEnd);
  211. /*
  212.     Requires IC 1.1.
  213.     You must specify a configuration before calling this routine.
  214.     You do not have to be inside an ICBegin/End pair to call this routine.
  215.     Parses a URL out of the specified text and feeds it off to the
  216.     appropriate helper.
  217.     hint indicates the default scheme for URLs of the form "name@address".
  218.     If hint is the empty string then URLs of that form are not allowed.
  219.     data points to the start of the text. It must not be nil.
  220.     len indicates the length of the text. It must be non-negative.
  221.     selStart and selEnd should be passed in as the current selection of
  222.     the text. This selection is given in the same manner as TextEdit,
  223.     ie if selStart = selEnd then there is no selection only an insertion
  224.     point. Also selStart ≤ selEnd and 0 ≤ selStart ≤ len and 0 ≤ selEnd ≤ len.
  225.     selStart and selEnd are returned as the bounds of the URL. If the
  226.     routine returns an error then these new boundaries may be
  227.     invalid but they will be close.
  228.     The URL is parsed out of the text and passed off to the appropriate
  229.     helper using the GURL AppleEvent.
  230. */
  231.  
  232. /* ***** Mappings Routines *****
  233.  * 
  234.  * Routines for interrogating mappings database.
  235.  * 
  236.  * ----- High Level Routines -----
  237.  */
  238.  
  239. ICError ICMapFilename(ICInstance inst,StringPtr filename,ICMapEntry* entry);
  240. /*
  241.     Requires IC 1.1.
  242.     You must specify a configuration before calling this routine.
  243.     If you are getting or setting multiple preferences, you should place
  244.     these calls within an ICBegin/ICEnd pair.
  245.     If you call this routine outside of such a pair, it implicitly
  246.     calls ICBegin(inst, icReadWritePerm).
  247.     Takes the name of an incoming file and returns the most appropriate
  248.     mappings database entry, based on its extension.
  249.     filename must not be the empty string.
  250.     Returns icPrefNotFoundErr if no suitable entry is found.
  251. */
  252.  
  253. ICError ICMapTypeCreator(ICInstance inst,OSType fType,OSType fCreator,StringPtr filename,ICMapEntry* entry);
  254. /*
  255.     Requires IC 1.1.
  256.     You must specify a configuration before calling this routine.
  257.     You must be inside an ICBegin/End pair to call this routine.
  258.     Takes the type and creator (and optionally the name) of an outgoing
  259.     file and returns the most appropriate mappings database entry.
  260.     The filename may be either the name of the outgoing file or
  261.     the empty string.
  262.     Returns icPrefNotFoundErr if no suitable entry found.
  263. */
  264.  
  265. /* ----- Mid Level Routines ----- */
  266.  
  267. ICError ICMapEntriesFilename(ICInstance inst,Handle entries,StringPtr filename,ICMapEntry* entry);
  268. /*
  269.     Requires IC 1.1.
  270.     You must specify a configuration before calling this routine.
  271.     You do not have to be inside an ICBegin/End pair to call this routine.
  272.     Takes the name of an incoming file and returns the most appropriate
  273.     mappings database entry, based on its extension.
  274.     entries must be a handle to a valid IC mappings database preference.
  275.     filename must not be the empty string.
  276.     Returns icPrefNotFoundErr if no suitable entry is found.
  277. */
  278.  
  279. ICError ICMapEntriesTypeCreator(ICInstance inst,Handle entries,OSType fType,OSType fCreator,StringPtr filename,ICMapEntry* entry);
  280. /*
  281.     Requires IC 1.1.
  282.     You must specify a configuration before calling this routine.
  283.     You do not have to be inside an ICBegin/End pair to call this routine.
  284.     Takes the type and creator (and optionally the name) of an outgoing
  285.     file and returns the most appropriate mappings database entry.
  286.     entries must be a handle to a valid IC mappings database preference.
  287.     The filename may be either the name of the outgoing file or
  288.     the empty string.
  289.     Returns icPrefNotFoundErr if no suitable entry found.
  290. */
  291.  
  292. /* ----- Low Level Routines ----- */
  293.  
  294. ICError ICCountMapEntries(ICInstance inst,Handle entries,long* count);
  295. /*
  296.     Requires IC 1.1.
  297.     You must specify a configuration before calling this routine.
  298.     You do not have to be inside an ICBegin/End pair to call this routine.
  299.     Counts the number of entries in the mappings database.
  300.     entries must be a handle to a valid IC mappings database preference.
  301.     count is set to the number of entries.
  302. */
  303.  
  304. ICError ICGetIndMapEntry(ICInstance inst,Handle entries,long ndx,long* pos,ICMapEntry* entry);
  305. /*
  306.     Requires IC 1.1.
  307.     You must specify a configuration before calling this routine.
  308.     You do not have to be inside an ICBegin/End pair to call this routine.
  309.     Gets the ndx'th entry in the mappings database.
  310.     entries must be a handle to a valid IC mappings database preference.
  311.     ndx must be in the range from 1 to the number of entries in the database.
  312.     The value of pos is ignored on input. pos is set to the position of
  313.     the ndx'th entry in the database and is suitable for passing back
  314.     into ICSetMapEntry.
  315.     Does not return any user data associated with the entry.
  316. */
  317.  
  318. ICError ICGetMapEntry(ICInstance inst,Handle entries,long pos,ICMapEntry* entry);
  319. /*
  320.     Requires IC 1.1.
  321.     You must specify a configuration before calling this routine.
  322.     You do not have to be inside an ICBegin/End pair to call this routine.
  323.     Returns the entry located at position pos in the mappings database.
  324.     entries must be a handle to a valid IC mappings database preference.
  325.     pos should be 0 to get the first entry. To get the subsequent entries, add
  326.     entry.total_size to pos and iterate.
  327.     Does not return any user data associated with the entry.
  328. */
  329.  
  330. ICError ICSetMapEntry(ICInstance inst,Handle entries,long pos,ICMapEntry* entry);
  331. /*
  332.     Requires IC 1.1.
  333.     You must specify a configuration before calling this routine.
  334.     You do not have to be inside an ICBegin/End pair to call this routine.
  335.     Sets the entry located at position pos in the mappings database.
  336.     entries must be a handle to a valid IC mappings database preference.
  337.     pos should be either a value returned from ICGetIndMapEntry or a value
  338.     calculated using ICGetMapEntry.
  339.     entry is a var parameter purely for stack space reasons. It is not
  340.     modified in any way.
  341.     Any user data associated with the entry is unmodified.
  342. */
  343.  
  344. ICError ICDeleteMapEntry(ICInstance inst,Handle entries,long pos);
  345. /*
  346.     Requires IC 1.1.
  347.     You must specify a configuration before calling this routine.
  348.     You do not have to be inside an ICBegin/End pair to call this routine.
  349.     Deletes the mappings database entry at pos.
  350.     entries must be a handle to a valid IC mappings database preference.
  351.     pos should be either a value returned from ICGetIndMapEntry or a value
  352.     calculated using ICGetMapEntry.
  353.     Also deletes any user data associated with the entry.
  354. */
  355.  
  356. ICError ICAddMapEntry(ICInstance inst,Handle entries,ICMapEntry* entry);
  357. /*
  358.     Requires IC 1.1.
  359.     You must specify a configuration before calling this routine.
  360.     You do not have to be inside an ICBegin/End pair to call this routine.
  361.     Adds an entry to the mappings database.
  362.     entries must be a handle to a valid IC mappings database preference.
  363.     The entry is added to the end of the entries database.
  364.     No user data is added.
  365. */
  366. #endif
  367.